Generar Análisis con IA

Este endpoint solicita la generación del análisis con IA de una Carpeta Tributaria: conclusiones y nivel de riesgo por sección (IVA, ventas, declaraciones e indicadores) más un resumen global. La generación es asíncrona: la respuesta confirma que el análisis quedó en proceso y el resultado se obtiene posteriormente.

• Opera sobre una sola Carpeta Tributaria en estado SUCCEEDED: por defecto la más reciente del RUT, o la indicada en carpetaTributariaId.
• Cada carpeta tiene un único análisis vigente. Regenerarlo es explícito (regenerate: true) y está limitado a 2 regeneraciones por carpeta.
• El resultado se obtiene consultando Análisis con IA Carpeta Tributaria (polling) y/o se recibe automáticamente vía webhook (processTaxFolderAnalysis).

Detalle de API

Request

• URL: /webhook/carpetaTributaria/{rut}/analisis
• Método: POST
• Content-Type: application/json

Parámetros

• rut (requerido, path): El RUT cuya Carpeta Tributaria se desea analizar. Formato del rut "12345678-9".

Cuerpo de la solicitud

El cuerpo es opcional. Si se omite, se analiza la Carpeta Tributaria SUCCEEDED más reciente del RUT.

Campo	Tipo	Requerido	Descripción
carpetaTributariaId	number	No	Identificador de la Carpeta Tributaria a analizar (entero mayor o igual a 1). Debe estar SUCCEEDED y pertenecer a tu alcance. Por defecto, la más reciente. Los identificadores se obtienen con Historial Carpeta Tributaria.
regenerate	bool	No	Debe ser true para volver a generar el análisis de una carpeta que ya tiene uno exitoso. Por defecto false.

Ejemplo request con curl

curl -X 'POST' \
  'https://prod.api.thesheriff.cl/api/clients/v2/webhook/carpetaTributaria/12345678-9/analisis' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9EjemploDeToken123' \
  -H 'x-client-identifier: SheriffSecureClient-v1' \
  -d '{
    "carpetaTributariaId": 12345,
    "regenerate": false
  }'

Response

Success

• Status code: 202

• Example response body:

  {
    "success": true,
    "data": {
      "carpetaTributariaId": 12345,
      "estado": "IN PROGRESS",
      "regenerations": 0
    }
  }

  A continuación se describen los campos devueltos en la respuesta JSON.

  Campo	Tipo	Descripción
  success	bool	Indica si la solicitud fue aceptada.
  data	object	Estado inicial del análisis solicitado.

  Campos dentro de data:

  Campo	Tipo	Descripción
  carpetaTributariaId	number	Identificador de la Carpeta Tributaria sobre la que se generará el análisis.
  estado	string	Estado del análisis. Al aceptar la solicitud es siempre IN PROGRESS.
  regenerations	number	Regeneraciones consumidas por esta carpeta, incluida la que se acaba de solicitar (máximo 2). 0 en el primer análisis.

  Reglas de regeneración

  El cupo de regeneraciones es por carpeta (carpetaTributariaId): cada Carpeta Tributaria tiene su propio contador, compartido con las regeneraciones que se soliciten desde la plataforma sobre esa misma carpeta. Se permiten como máximo 2 regeneraciones de un análisis exitoso; los reintentos de un análisis fallido no consumen cupo.

  Estado actual del análisis	regenerate	Resultado
  No existe (primer análisis)	—	Se genera. 202, regenerations: 0.
  SUCCEEDED, con cupo disponible	true	Se regenera. 202, regenerations aumenta en 1.
  SUCCEEDED, con cupo disponible	false u omitido	409: la carpeta ya tiene un análisis; se requiere regenerate: true.
  SUCCEEDED, sin cupo (2 regeneraciones)	cualquiera	400: se alcanzó el límite de regeneraciones.
  FAILED	—	Se reintenta. 202. No consume cupo ni requiere regenerate.
  IN PROGRESS	—	Se vuelve a encolar el mismo análisis. 202. No se crea uno duplicado ni consume cupo.

  info

  Durante una regeneración, Análisis con IA Carpeta Tributaria sigue devolviendo el resultado anterior (con estado: "IN PROGRESS") hasta que termine la nueva corrida.

  Entrega del resultado

  El análisis se procesa en segundo plano. Una vez finalizado, puedes obtener el resultado de dos formas:

  • Push (recomendado): Recibe el resultado automáticamente en tu URL mediante el webhook processTaxFolderAnalysis (tipo "Análisis con IA de carpeta tributaria"). Requiere tener un webhook activo de ese tipo configurado en la plataforma (ver Configurar Webhooks). El webhook solo se dispara para análisis solicitados por la API.
  • Pull: Consulta periódicamente Análisis con IA Carpeta Tributaria hasta que estado sea SUCCEEDED o FAILED.

  Payload del webhook

  Cuando el análisis termina correctamente, Sheriff envía un POST a tu URL con Content-Type: application/json y el siguiente cuerpo. Es el mismo contrato que el endpoint de consulta: no incluye el modelo de IA y las conclusiones vienen sin saltos de línea.

  {
    "identificador": 999,
    "carpetaTributariaId": 12345,
    "rut": "12345678-9",
    "estado": "SUCCEEDED",
    "resultado": {
      "iva": {
        "conclusiones": "El contribuyente declara IVA mensualmente y presenta sus formularios dentro de plazo en los últimos 12 períodos.",
        "riesgo": "Riesgo Bajo"
      },
      "ventas": {
        "conclusiones": "Las ventas netas muestran una tendencia creciente en el último año, sin caídas abruptas.",
        "riesgo": "Riesgo Bajo"
      },
      "declaraciones": {
        "conclusiones": "Las declaraciones de Renta de los últimos tres años fueron presentadas. Se observan diferencias menores entre F22 y F29.",
        "riesgo": "Riesgo Medio"
      },
      "indicadores": {
        "conclusiones": "La relación compras/ventas se mantiene estable en torno al 60%.",
        "riesgo": "Riesgo Bajo"
      },
      "resumenGlobal": {
        "conclusiones": "Contribuyente con comportamiento tributario regular, ventas crecientes y declaraciones al día.",
        "riesgo": "Riesgo Bajo"
      }
    },
    "error": null
  }

  Campo	Tipo	Descripción
  identificador	number	Identificador de la entrega del webhook. Es distinto en cada envío.
  carpetaTributariaId	number	Identificador de la Carpeta Tributaria analizada.
  rut	string	RUT del contribuyente.
  estado	string	SUCCEEDED.
  resultado	object	Conclusiones por sección. Misma estructura que en Análisis con IA Carpeta Tributaria.
  error	null	null cuando el análisis terminó correctamente.

  Si el análisis falla, el webhook entrega un aviso de error con este cuerpo:

  {
    "identificador": 999,
    "rut": "12345678-9",
    "error": "No se pudo generar el análisis de la Carpeta Tributaria."
  }

  Campo	Tipo	Descripción
  identificador	number	Identificador de la entrega del webhook.
  rut	string	RUT del contribuyente.
  error	string	Mensaje que describe el motivo del fallo.

  Un aviso de error se distingue por la presencia de error con contenido: no incluye resultado ni estado. Para asociarlo a la carpeta utiliza el header X-Sheriff-Event-Id, que incluye el carpetaTributariaId.

  Headers enviados por Sheriff

  • Content-Type: application/json
  • X-Sheriff-Event-Id: analisis:<carpetaTributariaId>:<timestamp>: identifica de forma única cada corrida del análisis.
  • Los headers que hayas configurado en tu webhook (por ejemplo, de autenticación).
  Una entrega por corrida

  Cada corrida del análisis, incluida cada regeneración, se entrega una vez y con un X-Sheriff-Event-Id distinto. Si recibes dos veces el mismo X-Sheriff-Event-Id (por ejemplo, por un reintento de entrega), trata la segunda como duplicada.

  Errores

  Para este endpoint:

  • 400: se alcanzó el límite de 2 regeneraciones para la carpeta, o el cuerpo es inválido (carpetaTributariaId no es un entero mayor o igual a 1, o regenerate no es booleano).
  • 404: no existe una Carpeta Tributaria SUCCEEDED para el RUT en tu alcance (o el carpetaTributariaId indicado no existe o no está SUCCEEDED).
  • 409: la carpeta ya tiene un análisis exitoso y no se envió regenerate: true.
  • 503: el servicio de procesamiento no está disponible; el análisis queda FAILED y puedes reintentarlo.

  400 - Solicitud inválida

  {
    "success": false,
    "code": 400,
    "error": "Se alcanzó el límite de 2 regeneraciones para este análisis."
  }

  401 - No autorizado

  {
    "success": false,
    "code": 401,
    "error": "No autorizado"
  }

  403 - No tienes permiso para acceder a este recurso

  {
    "success": false,
    "code": 403,
    "error": "No tienes permiso para acceder a este recurso"
  }

  404 - Recurso no encontrado

  {
    "success": false,
    "code": 404,
    "error": "No hay una carpeta tributaria procesada para este RUT."
  }

  408 - Tiempo de espera agotado

  {
    "success": false,
    "code": 408,
    "error": "Tiempo de espera agotado"
  }

  409 - Conflicto

  {
    "success": false,
    "code": 409,
    "error": "Esta carpeta ya tiene un análisis. Usá regenerate=true para regenerarlo."
  }

  429 - Demasiadas solicitudes

  {
    "success": false,
    "code": 429,
    "error": "Demasiadas solicitudes"
  }

  500 - Error interno del servidor

  {
    "success": false,
    "code": 500,
    "error": "Error interno del servidor"
  }

  503 - Servicio no disponible

  {
    "success": false,
    "code": 503,
    "error": "No se pudo encolar el análisis: el servicio de procesamiento no está disponible."
  }